home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / mg2a_src.zip / MGPROG.DOC < prev    next >
Text File  |  1988-08-23  |  11KB  |  296 lines
  1. This documentation covers mg 2a.
  2.  
  3. I do want feedback from other mg developers on what they think of my
  4. changes, documentation, and what needs to be done to make mg better.
  5. This document is not complete, it mainly covers the areas I have
  6. recently changed.
  7.  
  8. Possible future changes:
  9.  
  10. Rearange file contents along more rational lines.  Further split the
  11. monolithic def.h file.
  12.  
  13. Changing the echo line stuff to use a minibuffer keymap.
  14.  
  15. Making the kill buffer a linked list of lines.
  16.  
  17. Variables.
  18.  
  19. Allow for backspace, ^s, etc. to be changed in some reasonable manner.
  20. (Probably using variables or a simulation thereof.)  I do not think an
  21. input keymap is the correct solution, even if it is frequently used in
  22. Gnu emacs.  (Besides the extra overhead, keynames come out wrong.)
  23.  
  24. Make long lines wrap like they do in GNU emacs.
  25.  
  26. Fix known (and unknown :-) bugs.
  27.  
  28. Have the keymaps and associated tables generated by a program.
  29.  
  30.  
  31. Known bugs/limitations:
  32.  
  33. Binding a key in a named keymap may or may not change the binding of
  34. other keys pointing to the same keymap.     (i.e. if ^H and ^_ are bound
  35. to help, rebinding ^Hb may not (or may) change ^_b.  This can be cured
  36. by rebinding ^_ to help.)
  37.  
  38. Overwrite mode does not work in macros.     (Characters are inserted
  39. rather than overwriting.)
  40.  
  41. Dired mode has some problems:  Rename does not update the buffer.
  42. Doing a dired again will update the buffer (whether it needs it or
  43. not) and will lose any marks for deletion.  .. and . are not
  44. recognized as special cases.
  45.  
  46.  
  47.  
  48. New implementation oddities:
  49.  
  50. insert and define-key are new commands corresponding to the mocklisp
  51. functions in Gnu Emacs.     (Mg does not have non-command functions.)
  52. (Mg's insert will only insert one string.)
  53.  
  54. The display wrap code does not work at all like that of GNU emacs.
  55.  
  56.  
  57.  
  58. Adding command functions to mg:
  59.  
  60. Command functions take two integer aguments and return an integer.
  61. The first argument, f, is a set of flags.  (f&FFARG) is non-zero if a
  62. numeric arguement was passed to the function.  (There are bits
  63. indicating how the agument was specified, but they are not fully
  64. impleminted.)  (f&FFRAND) is non-zero if the function is being called
  65. by another function and that possibly slightly different action should
  66. be taken.  (No error checking, supress output, etc.)  The second
  67. argument, n, is the numeric agument passed or one if there was no
  68. numeric arugment.  The fuction should return TRUE if it executes
  69. correctly, FALSE if it could not, and ABORT if the user typed the
  70. keyboard quit character at a prompt.
  71.  
  72. The function must be added to the functnames table in keymap.c.     This
  73. table must be kept in assending ascii sequence.
  74.  
  75.  
  76.  
  77. Key maps:
  78.  
  79. Key maps are structures containing information on what action should
  80. be taken corresponding to an individual keypress.  That action could
  81. be an indication that this is a prefix key and the next kepress should
  82. be looked up in another keymap.
  83.  
  84.     Example keymap:
  85.  
  86.     static    struct    KEYMAPE(6+IMAPEXT)    cXmap = {
  87.         6,
  88.         6+IMAPEXT,
  89.         rescan,
  90.         {
  91.             {CCHR('B'),CCHR('G'),    cXcB,    (KEYMAP *)NULL},
  92.             {CCHR('L'),CCHR('X'),    cXcL,    (KEYMAP *)NULL},
  93.             {'(',    ')',        cXlp,    (KEYMAP *)NULL},
  94.             {'0',    '4',        cX0,    (KEYMAP *)&cX4map},
  95.             {'=',    '=',        cXeq,    (KEYMAP *)NULL},
  96.             {'^',    's',        cXcar,    (KEYMAP *)NULL},
  97.         }
  98.     };
  99.  
  100. (Note: this example is a simplified example of a real keymap in keymap.c.)
  101.  
  102. Since C does not directly support structures containing undementioned
  103. arrays, the macro KEYMAPE is used to create a structure with an array
  104. of the proper size.  6 is the current size of the array, and IMAPEXT
  105. is the number of extra elements left for future groth (by rebinding
  106. keys) before the map must be reallocated.  rescan is the function to
  107. be executed if a specific entry for the key is not found.  (rescan is
  108. a special function that searches for something else to do -- first by
  109. trying lowercasing the last character in the keymap, then by trying
  110. the other modes in effect.)
  111.  
  112. The array elements must be in order by the keys they define.  Each
  113. covers a range of characters.  Numeric values should not be used for
  114. characters, they make porting mg to some other systems harder.    The
  115. CCHR macro may be used to specify control characters, including DEL
  116. (CCHR('?')).  cXcB, cXcL, etc. are arrays of pointers to functions
  117. returning int.    One of these fuction pointers per element may be to
  118. the pseuto-function prefix.  cX4map is the keymap coresponding to the
  119. prefix function bound to '4' in this keymap.  Having several keys in
  120. an element bound to the default function is better than increasing the
  121. number of elements.
  122.  
  123.  
  124.  
  125. Modes:
  126.  
  127. Modes are named key maps that are scanned for key bindings before the
  128. global keymap is.  There are functions in modes.c to toggle modes on
  129. or off for individual buffers.  Note that the "major"/"minor" mode
  130. distiction is different than in Gnu Emacs.  Dired is currently the
  131. only major mode available, buffers are put into dired mode on creation
  132. by the dired code.  (The distiction in mg is the major mode replaces
  133. the default keymap instead of being an overlay.) Some modes (overwrite
  134. and no-tab) also trigger per-buffer flags that should be convered to
  135. per-buffer variables when we add variables.  Keymaps for the modes are
  136. kept in keymap.c with the other keymaps.
  137.  
  138.  
  139.  
  140. System dependent files:
  141.  
  142. Fileio.c:
  143.     Contains file i/o routines:
  144.         ffputbuf(BUFFER *):
  145. Write all lines of buffer to the file.    The last line of the buffer does
  146. NOT have the normally implied newline.    (One may be added if
  147. nessisary, but don't write out the last line if it is zero characters
  148. long.)
  149.  
  150.         ffgetline(char *buf, int nbuf, int *nbytes):
  151. Read a line from the file up to the length specified by the second
  152. argument in to the buffer pointed to by the first.  If a newline is
  153. not found after reading nbuf characters, return FIOLONG and on the
  154. next call to ffgetline return the remaining portion (or nbuf more
  155. characters and return FIOLONG).     If a newline is found, set *nbytes to
  156. the number of characters read and return FIOSUC.  If the end of file
  157. is descovered, set *nbytes and return FIOEOF.  (If the file ends in a
  158. newline, the call returning FIOEOF will set *nbytes to 0.)  If any
  159. other error occurs, return FIOERR.
  160.  
  161.         char *adjustname(char *fname)
  162. Standardize filename.  On mono-case systems, lowercase the file name.
  163. If NO_DIR is not defined, make fully qualified.     (not relitive to the
  164. current directory, which may change.)
  165.  
  166.         fncmp(char *fna, char *fnb) 
  167. Return 0 if both arguments refer to the same file or buffer.  #define
  168. it to be strcmp on mono-case or case sensitive systems, use a non-case
  169. sensitive compareison otherwise.  (Borrow it from the osk fileio.c)
  170. Both arguments have been through adjustname already. 
  171.  
  172.     routines needed for dired:
  173.  
  174.         rename(char *fromname, char *toname)
  175. rename file.  BSD systems have this as a system call.  return -1 on
  176. error.
  177.  
  178.         copy(char *fromname, char *toname)
  179. copy file.  return -1 on error.
  180.  
  181.         unlinkdir(char *name)
  182. Delete directory.  return -1 on error.  (possibly including non-empty
  183. directory.)
  184.  
  185.         BUFFER *dired_(char *name)
  186. Create dired buffer for named directory.  See example from osk or bsd.
  187.  
  188.         d_makename(LINE *l, char *fname)
  189. Concatinate directory name associated with the current dired BUFFER
  190. with file name in line.  Return ABORT if no file name on line, FALSE
  191. if it is an ordinary file, or TRUE if there is a directory.  Name made
  192. should be the same as if it were run through adjustname. 
  193.  
  194.  
  195. Converting system & terminal dependent files from mg1b:
  196.  
  197. All command functions will have to be rewritten to use the new two
  198. argument calling sequence.  (Some compilers will let you get away
  199. without doing this for testing purposes.  Problems, if any, will show
  200. up at run-time.)
  201.  
  202. Key binding is completly different.  See extend.c if your code needs
  203. to do rebinding.
  204.  
  205. I have attempted make mg less dependant on ascii character values.
  206. Keymap.c depends on ascii sorting order.  Cinfo.c depends on character
  207. values and contains a function to convert from a character value
  208. to a key name.  Several modules assume